/*
 *  linux/fs/open.c
 *
 *  (C) 1991  Linus Torvalds
 */

#include <string.h>         // 字符串头文件 主要定义了一些有关字符串操作的嵌入函数
#include <errno.h>          // 错误号头文件 包含系统中各种出错号 （Linus从MINIX中引进的）
#include <fcntl.h>          // 文件控制头文件 用于文件及其描述符的操作控制常数符号的定义
#include <sys/types.h>      // 类型头文件 定义了基本的系统数据类型
#include <utime.h>          // 用户时间头文件 定义了访问和修改时间结构以及utime（）原型
#include <sys/stat.h>       // 文件状态头文件 含有文件或文件系统状态结构stat和常量

#include <linux/sched.h>    // 调度程序头文件 定义任务结构 task_struct 初始任务0的数据
#include <linux/tty.h>      // tty头文件 定义了有关tty_io串行通信方面的参数 常数
#include <linux/kernel.h>   // 内核头文件 含有一些内核常用函数的原形定义
#include <asm/segment.h>    // 段操作头文件 定义了有关段寄存器操作的嵌入式汇编函数
// 取文件系统信息系统调用函数
int sys_ustat(int dev, struct ustat * ubuf)
{
	return -ENOSYS;
}
// 如果文件访问和修改时间 参数filename是文件名 times是访问和修改时间结构指针 如果times指针不为NULL 则取utimbuf结构中的时间信息来设置文件的访问和修改时间 如果times指针是NULL则取系统当前时间来设置指定文件的访问和修改时间域
int sys_utime(char * filename, struct utimbuf * times)
{
	struct m_inode * inode;
	long actime,modtime;
    // 根据文件名寻找对应的i节点 如果没有找到 则返回出错码
	if (!(inode=namei(filename)))
		return -ENOENT;
	if (times) {    // 如果访问和修改时间 数据结构指针不为NULL 则从结构中读取用户设置的时间值
		actime = get_fs_long((unsigned long *) &times->actime);
		modtime = get_fs_long((unsigned long *) &times->modtime);
	} else  // 否则将访问和修改时间置位当前时间
		actime = modtime = CURRENT_TIME;
	inode->i_atime = actime;    // 修改i节点中的访问时间字段和修改时间字段
	inode->i_mtime = modtime;
	inode->i_dirt = 1;          // 置 i 节点已修改标志 释放该i节点 并返回0
	iput(inode);
	return 0;
}

/*  // 文件属性xxx 我们该用真实用户id还是有效用户id BSD系统使用了真实用户id 以使该调用可以供setuid程序使用 （注：POSIX标准建议使用真实用户ID）
 * XXX should we use the real or effective uid?  BSD uses the real uid,
 * so as to make this call useful to setuid programs.
 */ // 检查对文件的访问权限 参数：filename-文件名 mode-屏蔽码 由 R_OK（4） W_OK（2）X_OK（1）和 F_OK(0)组成  如果请求允许访问的话 则返回0 否则返回出错码
int sys_access(const char * filename,int mode)
{
	struct m_inode * inode;
	int res, i_mode;

	mode &= 0007;       // 屏蔽码由低3位组成 因此清楚所有高比特位
	if (!(inode=namei(filename)))   // 如果文件名对应的i节点不存在 则返回出错码
		return -EACCES;
	i_mode = res = inode->i_mode & 0777;    // 取文件的属相码 并释放该i节点
	iput(inode);
	if (current->uid == inode->i_uid)   // 如果当前进程是该文件的宿主 则取文件宿主属性
		res >>= 6;
	else if (current->gid == inode->i_gid)  // 否则如果当前进程是与该文件同属一组 则取文件组属性
		res >>= 6;
	if ((res & 0007 & mode) == mode)    // 如果文件属性具有查询的属性位 则访问许可 返回0
		return 0;
	/*  // 我们最后才对xxx作下面的测试 因为我们实际上需要交换有效用户id和真实用户id（临时的）然后才调用suser（）函数 如果我们确实要调用suser（）函数 则需要最后才被调用
	 * XXX we are doing this test last because we really should be
	 * swapping the effective with the real user id (temporarily),
	 * and then calling suser() routine.  If we do call the
	 * suser() routine, it needs to be called last. 
	 */ // 如果当前用户id为0（超级用户）并且屏蔽码执行位0或文件可以被任何人访问 则返回0
	if ((!current->uid) &&
	    (!(mode & 1) || (i_mode & 0111)))
		return 0;
	return -EACCES; // 否则返回出错码
}
// 改变当前工作目录系统调用函数 参数：filename-目录名 操作成功则返回0 否则返回出错码
int sys_chdir(const char * filename)
{
	struct m_inode * inode;
    // 如果文件名对应的i节点不存在 则返回出错码
	if (!(inode = namei(filename)))
		return -ENOENT;
	if (!S_ISDIR(inode->i_mode)) {  // 如果该i节点不是目录的i节点 则释放该节点 返回出错码
		iput(inode);
		return -ENOTDIR;
	}
	iput(current->pwd); // 释放当前进程原工作目录i节点 并指向该新置的工作目录i节点 返回0
	current->pwd = inode;
	return (0);
}
// 改变根目录系统调用函数 将指定的路径名改为根目录 如果操作成功则返回0 否则返回出错码
int sys_chroot(const char * filename)
{
	struct m_inode * inode;
    // 如果文件名对应的i节点不存在 则返回出错码
	if (!(inode=namei(filename)))
		return -ENOENT;
	if (!S_ISDIR(inode->i_mode)) {  // 如果该i节点不是目录的i节点 则释放该节点 返回出错码
		iput(inode);
		return -ENOTDIR;
	}
	iput(current->root);    // 释放当前进程的根目录i节点 并重置为这里指定目录名的i节点 返回0
	current->root = inode;
	return (0);
}
// 修改文件属性系统调用函数 参数：filename-文件名 mode-新的文件属性 若操作成功则返回0 否则返回出错码
int sys_chmod(const char * filename,int mode)
{
	struct m_inode * inode;
    // 如果文件名对应的i节点不存在 则返回出错码
	if (!(inode=namei(filename)))
		return -ENOENT;
	if ((current->euid != inode->i_uid) && !suser()) {  // 如果当前进程的有效用户id不等于文件i节点的用户id 并且当前进程不是超级用户 则释放该文件i节点 返回出错码
		iput(inode);
		return -EACCES;
	}   // 重新设置i节点的文件属性 并置该i节点已修改标志 释放该i节点 返回0
	inode->i_mode = (mode & 07777) | (inode->i_mode & ~07777);
	inode->i_dirt = 1;
	iput(inode);
	return 0;
}
// 修改文件宿主系统调用函数 参数：filename-文件名 uid是用户标识符（用户id）gid是组id 若操作成功则返回0 否则返回出错码
int sys_chown(const char * filename,int uid,int gid)
{
	struct m_inode * inode;
    // 如果文件名对应的i节点 则返回出错码
	if (!(inode=namei(filename)))
		return -ENOENT;
	if (!suser()) { // 若当前进程不是超级用户 则释放该i节点 返回出错码
		iput(inode);
		return -EACCES;
	}   // 设置文件对应i节点的用户id和组id 并置i节点已经修改标志 释放该i节点 返回0
	inode->i_uid=uid;
	inode->i_gid=gid;
	inode->i_dirt=1;
	iput(inode);
	return 0;
}
// 打开（或创建）文件系统调用函数 参数：filename-是文件名 flag-打开文件标志 只读O_RDONLY 只写O_WRONLY 或读写ORWR 以及 O_CREAT O_EXCL O_APPEND 等其他一些标志的组合 若本函数创建了一个新文件 在mode用于指定使用文件的许可属性
int sys_open(const char * filename,int flag,int mode)
{
	struct m_inode * inode;
	struct file * f;
	int i,fd;
    // 将用户设置的模式与进程的模式屏蔽码相与 产生许可的文件模式
	mode &= 0777 & ~current->umask;
	for(fd=0 ; fd<NR_OPEN ; fd++)   // 搜索进程结构中文件结构指针数组 查找一个空闲项 若已经没有空闲项 则返回出错码
		if (!current->filp[fd])
			break;
	if (fd>=NR_OPEN)
		return -EINVAL;
	current->close_on_exec &= ~(1<<fd); // 设置执行时关闭文件句柄位图 复位对应比特位
	f=0+file_table; // 令 f 指向文件表数组开始处 搜索空闲文件结构项（句柄引用计数为0的项）若已经没有空闲文件表结构项 则返回出错码
	for (i=0 ; i<NR_FILE ; i++,f++)
		if (!f->f_count) break;
	if (i>=NR_FILE)
		return -EINVAL;
	(current->filp[fd]=f)->f_count++;   // 让进程的对应文件句柄的文件结构指针只想搜索到的文件结构 并令句柄引用计数递增1
	if ((i=open_namei(filename,flag,mode,&inode))<0) {  // 调用函数执行打开操作 若返回值小于0 则说明出错 释放刚申请到的文件结构 返回出错码
		current->filp[fd]=NULL;
		f->f_count=0;
		return i;
	}   // ttys 有些特殊（ttyxx主号==4 tty主号==5）
/* ttys are somewhat special (ttyxx major==4, tty major==5) */
	if (S_ISCHR(inode->i_mode)) // 如果是字符设备文件 那么如果设备号是4的话 则设置当前进程的tty号为该i节点的子设备号 并设置当前进程tty对应的tty表项的父进程组号等于进程的父进程组号
		if (MAJOR(inode->i_zone[0])==4) {
			if (current->leader && current->tty<0) {
				current->tty = MINOR(inode->i_zone[0]);
				tty_table[current->tty].pgrp = current->pgrp;
			}   // 否则 如果该字符文件设备是5的话 若当前进程没有tty 则说明出错 释放i节点和申请到的文件结构返回 出错码
		} else if (MAJOR(inode->i_zone[0])==5)
			if (current->tty<0) {
				iput(inode);
				current->filp[fd]=NULL;
				f->f_count=0;
				return -EPERM;
			}   // 同样对于块设备文件： 需要检查盘片是否被更换 若更换则需要让高速缓冲区中对应该设备的所有缓冲块失效
/* Likewise with block-devices: check for floppy_change */
	if (S_ISBLK(inode->i_mode)) // 初始化文件结构 置文件结构属性和标志 置句柄引用计数 1 设置i节点字段 文件读写指针初始化为0 返回文件句柄
		check_disk_change(inode->i_zone[0]);
	f->f_mode = inode->i_mode;
	f->f_flags = flag;
	f->f_count = 1;
	f->f_inode = inode;
	f->f_pos = 0;
	return (fd);
}
// 创建文件系统调用函数 参数 pathname-路径名 mode与上面的sys_open（）函数相同
int sys_creat(const char * pathname, int mode)
{
	return sys_open(pathname, O_CREAT | O_TRUNC, mode);
}
// 关闭文件系统调用函数 参数：fd-文件句柄 成功则返回0 否则返回出错码
int sys_close(unsigned int fd)
{	
	struct file * filp;
    // 若文件句柄值大于程序同事能打开的文件数 则返回出错码
	if (fd >= NR_OPEN)
		return -EINVAL;
	current->close_on_exec &= ~(1<<fd); // 复位进程的执行时关闭文件句柄图对应位
	if (!(filp = current->filp[fd]))    // 若该文件句柄对应的文件结构指针是NULL 则返回出错码
		return -EINVAL;
	current->filp[fd] = NULL;           // 置该文件句柄的文件结构指针为NULL
	if (filp->f_count == 0)     // 若在关闭文件之前 对应文件结构中句柄引用计数已经为0 则说明内核出错 死机
		panic("Close: file count is 0");
	if (--filp->f_count)    // 否则将对应文件结构的句柄引用计数减1 如果还不为0 则返回0（成功） 若已等于0 说明该文件已经没有句柄 引用 则释放该文件i节点 返回0
		return (0);
	iput(filp->f_inode);
	return (0);
}
